home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Scope / Scope Disk #142 (199x)(Scope PD)(US)[WB].zip / Scope Disk #142 (199x)(Scope PD)(US)[WB].adf / LoadImage / RexxHost.doc < prev    next >
Text File  |  1990-07-30  |  16KB  |  378 lines
  1. ====================== RexxHost.Library v34.12 =======================
  2. ======================================================================
  3. An Amiga shared library for creating/managing ARexx host environments.
  4. ======================================================================
  5.  
  6. ========================== IMPORTANT NOTICE ==========================
  7. ======================================================================
  8. This is the official new release of rexxhost.library.  Due to register
  9. rearrangements  programs compiled using the old 1.6 release have to be
  10. recompiled  or  serious  system  crashes  will  result!  Note that the
  11. supplied library code can only be recompiled under Aztec 'C' 5.0.
  12.  
  13. ============================= Background =============================
  14. ======================================================================
  15. A  friend  of mine was busy developing a stock management program when
  16. he suddenly realized that an ARexx interface would be the only feature
  17. that wasn't already part of his project.  So he started to analyze, to
  18. program,  to  try - just to find out that it would be too much work to
  19. add it.
  20.         Some  months later a programmer who works for the same company
  21. I  am  working  for decided to rewrite his home-brewn assembler/linker
  22. program  to  interface to CygnusEd Professional.  The problem is:  his
  23. program  is written in assembly language, the standard host management
  24. routines are written in 'C'...
  25.         To  simplify  the host creation/management procedure I decided
  26. to  put the required routines as well as some extra code into a shared
  27. library,  easy  to  use  by  ANY  language (can you imagine AmigaBASIC
  28. controlling AmigaTeX?).
  29.         As  soon  as the Aztec 'C' 5.0 update came in, the library has
  30. been  updated  to  take  advantage  of  the  new compiler features.  I
  31. suppose  the  source  code  can  be  seen  as  a  real  'treasure' for
  32. programmers  who also wish to build shared libraries with the new Manx
  33. compiler but find the original Manx support code too confusing.
  34.  
  35. ========================= Supplied material ==========================
  36. ======================================================================
  37.  
  38.         The RexxHostLib package contains the following files:
  39.         -----------------------------------------------------
  40.         FancyDemo.............. Demonstration program
  41.         FancyDemo.c............ Source code for demonstration program
  42.  
  43.         LibStartup.asm......... Library support code
  44.  
  45.         LibMain.c.............. Library support code
  46.         PreInclude.c........... Source for precompiled header
  47.                                 file
  48.         RexxHostLib.c.......... Library support code
  49.         rexxhostbase.h......... Library header file
  50.         StringAsm.asm.......... Assembly language string routines
  51.  
  52.         rexxhostlat.lib........ Lattice 'C' linker library
  53.         rexxhostnew.lib........ Aztec 'C' 5.0 linker library
  54.         rexxhostold.lib........ Aztec 'C' 3.6 linker library
  55.  
  56.         rexxhost.library....... Amiga shared library
  57.  
  58.         MakeFile............... Library building-instructions
  59.  
  60.         RexxHost.fd............ Library function definitions
  61.  
  62.         TestDemo.rexx.......... ARexx demonstration script
  63.  
  64.         RexxHost.doc........... This file
  65.  
  66.         Glue................... Subdirectory containing library
  67.                                 glue routine source codes
  68.  
  69. ============================= How to use =============================
  70. ======================================================================
  71. The  rexxhost.library needs ARexx (any version will do, v1.10 is best)
  72. to  work properly.  It needs to be opened EXPLICITELY, i.e.  it is not
  73. forced  into  memory by the ARexx server and CANNOT be loaded with the
  74. ADDLIB() call in rexx-scriptfiles.  An unlimited number of callers may
  75. open   the   library,   it   is   100%   reentrant.    Just  like  the
  76. rexxsyslib.library   the   rexxhost.library   stays  in  memory  until
  77. explicitely expunged (e.g.  via "flushlibs" call from Workbench).
  78.         The  OpenLibrary()  call  returns  a pointer to a RexxHostBase
  79. structure (as defined in the rexxhostbase.h include file).  It has the
  80. following format:
  81.  
  82.                 struct RexxHostBase
  83.                 {
  84.                         struct Library   LibNode;
  85.                         struct RxsLib   *RexxSysBase;
  86.                 };
  87.  
  88. The  pointer  to the RxsLib structure represents a pointer to the base
  89. of  rexxsyslib.library.   It  can  be  copied  by the calling process,
  90. rexxsyslib.library does not need to be opened explicitely.
  91.         All library functions are "bullet proof", i.e. if the supplied
  92. arguments  are  illegal  the  functions return immediately.  Note that
  93. this  library  only  contains  basic support functions, you will still
  94. have  to  do  command analysis, parsing and command processing on your
  95. own (which isn't difficult, look at the DClockHandler.c sourcecode for
  96. an example).
  97.  
  98. ============================= Compiling ==============================
  99. ======================================================================
  100. A  Makefile  for  Aztec  'C'  5.0 is supplied.  This version CANNOT be
  101. recompiled under compiler versions previous to 5.0.  Note that line 67
  102. in the ARexx 'C' include file 'rxslib.h' has to be changed from:
  103.  
  104.         WORD rl_NumMsg; /* pending count */
  105.  
  106. to:
  107.  
  108.         WORD rl_PgmMsg; /* pending count */
  109.  
  110. or  you  will  get  a 'multiple entry' message from the compiler (Bill
  111. obviously overlooked the misspelled entry).
  112.  
  113. ===================== RexxHost.Library Functions =====================
  114. ======================================================================
  115.  
  116. CreateRexxHost - Create a RexxHost with supplied name
  117.  
  118. Usage:
  119. RexxHost = CreateRexxHost(HostName)
  120.   D0                         A0
  121.  
  122. This  function  tries  to  allocate a public messageport with a unique
  123. name.   If  a  port  with the supplied name does already exist NULL is
  124. returned.   The  name of the HostPort to be created is copied so there
  125. is  no  need  to  keep  it  statically initialized in you application.
  126. Note:   NEVER use this function if you only want to allocate a general
  127. purpose  MsgPort.   Some  additional  type  checking  is  done in this
  128. routine.   A  RexxHost  is  an  extended  MsgPort  structure with some
  129. additional  data  which allows all library functions to test if a host
  130. address  is valid.  You should rather see a RexxHost as a MsgPort.  Do
  131. not  rely  on  the  existence  of  the  flags  following  the  MsgPort
  132. structure.
  133.  
  134.  
  135. DeleteRexxHost - Remove RexxHost
  136.  
  137. Usage:
  138. NULL = DeleteRexxHost(RexxHost)
  139.  D0              A0
  140.  
  141. A  supplied  RexxHost  is  removed  from the system, freeing allocated
  142. signals  and  nodes.  A NULL-pointer is always returned so user can do
  143. 'Host  =  DeleteRexxHost(Host);'.  Never use this function to remove a
  144. general   purpose   MsgPort  from  the  system  list,  in  which  case
  145. DeleteRexxHost()  is  guaranteed  to  return immediately without doing
  146. anything.
  147.  
  148.  
  149. SendRexxCommand() - Send a command to the rexx server
  150.  
  151. Usage:
  152. Success = SendRexxCommand(RexxHost,CommandString,FileExtension,HostName)
  153.   D0                         A0          A1             A2        A3
  154.  
  155. This  function  causes  the  rexx  server  to  execute  a script file.
  156. HostPort  must  point  to the host RexxHost, CommandString points to a
  157. string   containing   the   name   of  the  command  to  be  executed.
  158. FileExtension   and   HostName   are   optional   and   may  be  NULL.
  159. FileExtension  defines  the  script  file name extension for this host
  160. (for  standard rexx scripts this is ".rexx", for CygnusEd Professional
  161. it  is  ".ced").   HostName  is  supplied to allow the host to address
  162. different  sub-hosts, such as different windows a text editor may have
  163. open.  This function returns FALSE (= 0) if the command cannot be sent
  164. (rexx  may  not  be  running)  and  TRUE (= 1) if the message has been
  165. posted.
  166.  
  167.  
  168. FreeRexxCommand() - Free the contents of a RexxMsg
  169.  
  170. Usage:
  171. FreeRexxCommand(RexxMessage)
  172.                     A0
  173.  
  174. Having  successfully  called  SendRexxCommand()  the  rexx server will
  175. return the RexxMsg with result flags set.  This kind of message cannot
  176. be  replied (since it already has been replied by the rexx server) but
  177. has  to  be  deallocated.   Be  sure  to examine the result code flags
  178. before you remove the RexxMsg.
  179.  
  180.  
  181. ReplyRexxCommand() - Returns a RexxMsg to the rexx server
  182.  
  183. Usage:
  184. ReplyRexxCommand(RexxMessage,Primary,Secondary,Result)
  185.                      A0         D0      D1       A1
  186.  
  187. Having received a command from the rexx server the host has to process
  188. it.  After that the RexxMsg has to be replied so the rexx server knows
  189. about  the  result.  Primary and Secondary are the values to be passed
  190. in  the  result flags of the RexxMsg structure, Result is optional and
  191. may  be  NULL.   It  usually  points to a string containing the result
  192. (numeric or string) of the command having been executed.
  193.  
  194.  
  195. GetRexxCommand() - Get the first argument from a RexxMsg
  196.  
  197. Usage:
  198. String = GetRexxCommand(RexxMessage)
  199.   D0                        A0
  200.  
  201. This  function  is  supported to save the calling program from dealing
  202. with  pointer  offsets  (which  may  be  difficult  with some language
  203. implementations).  It returns a pointer to the first argument entry in
  204. the  supplied  RexxMsg  structure.   This  is  usually a command to be
  205. executed by the host.  If NULL is returned then the RexxMsg is a reply
  206. to a former SendRexxCommand() command.
  207.  
  208.  
  209. GetRexxArg() - Get the first argument from a RexxMsg
  210.  
  211. Usage:
  212. String = GetRexxArg(RexxMessage)
  213.   D0                    A0
  214.  
  215. This  function  is  supported to save the calling program from dealing
  216. with  pointer  offsets  (which  may  be  difficult  with some language
  217. implementations).  It returns a pointer to the first argument entry in
  218. the  supplied RexxMsg structure.  This function is almost identical to
  219. GetRexxCommand(),  the  string  pointer is always returned, no RexxMsg
  220. type consideration is done.
  221.  
  222.  
  223. GetRexxResult1() - Get the first RexxMsg result code
  224.  
  225. Usage:
  226. Result = GetRexxResult1(RexxMessage)
  227.   D0                        A0
  228.  
  229. This  function  is  supported to save the calling program from dealing
  230. with  pointer  offsets  (which  may  be  difficult  with some language
  231. implementations).  It returns the value of the first result code entry
  232. in the supplied RexxMsg structure.
  233.  
  234.  
  235. GetRexxResult2() - Get the second RexxMsg result code
  236.  
  237. Usage:
  238. Result = GetRexxResult2(RexxMessage)
  239.   D0                        A0
  240.  
  241. This  function  is  supported to save the calling program from dealing
  242. with  pointer  offsets  (which  may  be  difficult  with some language
  243. implementations).   It  returns  the  value  of the second result code
  244. entry in the supplied RexxMsg structure.
  245.  
  246.  
  247. GetToken() - Get the next argument from a string
  248.  
  249. Usage:
  250. Argument = GetToken(String,StartChar,AuxBuff,MaxLength)
  251.    D0                 A0      A1       A2       D0
  252.  
  253. GetToken()  implements easy argument parsing.  ARexx posts commands as
  254. NULL-terminated   strings   with   arguments   separated   by  spaces.
  255. GetToken()  takes  a pointer to the command string (String), a pointer
  256. to  a  counter  variable  (StartChar,  must be a long), a pointer to a
  257. buffer the next argument will be copied to (AuxBuff) and the length of
  258. the  buffer  the  next  argument  will  be copied to (MaxLength).  The
  259. result  will be a pointer to AuxBuff if an argument was found, NULL if
  260. the  end of the command string was reached.  You are to make sure that
  261. the string pointed to by AuxBuff is long enough to hold the arguments.
  262.  
  263.  
  264. GetStringValue() - Return the numeric value of a string
  265.  
  266. Usage:
  267. Value = GetStringValue(String)
  268.   D0                     A0
  269.  
  270. Just  like the 'C' language atoi() function GetStringValue() evaluates
  271. the contents of a string.  Its value is returned as a long word.  This
  272. function  helps  to  analyze  the contents of a RexxMsg result code or
  273. command argument.
  274.  
  275.  
  276. BuildValueString() - Turns a numeric value into a string
  277.  
  278. Usage:
  279. String = BuildValueString(Value,String)
  280.   D0                        D0    A0
  281.  
  282. This  function helps to build a string from a numeric value, just like
  283. the  'C'  language  itoa() function.  The supplied string must be long
  284. enough  to  hold  the digits built from Value.  A pointer to the built
  285. string is returned.
  286.  
  287.  
  288. RexxStrCmp() - Compare two strings ignoring case
  289.  
  290. Usage:
  291. Match = RexxStrCmp(String1,String2)
  292.   D0                 A0      A1
  293.  
  294. This  function  is  intended  to be a replacement for the 'C' function
  295. strcmp().   Other than the builtin strcmp, RexxStrCmp ignores the case
  296. of  both  strings  and even handles international characters correctly
  297. (i.e.   RexxStrCmp("äöüß","ÄÖÜß")  == 0).  The value returned as Match
  298. is  0  if both strings are considered equal, any other value indicates
  299. that both strings are different.
  300.  
  301. ============================== Nuisance ==============================
  302. ======================================================================
  303. The library could be shorter if the  Aztec 'C' linker  'LN'  generated
  304. proper hunks:
  305.  
  306. 1) DATA  and  BSS hunks are intermixed; as a result the BSS hunk turns
  307.    out to have length zero which will still force DOS to allocate four
  308.    extra bytes which are never used.
  309.  
  310. 2) Additionally  the  DATA/BSS  hunk has to be zeroed 'manually' which
  311.    requires some extra code in crt0.a68.
  312.  
  313. 3) Even  if  you  don't  request a BSS hunk the linker still generates
  314.    one.    The  -  empty  -  hunk  (including  superfluous  relocation
  315.    information) occupies disk space it doesn't need.
  316.  
  317.        Is there any chance this 'kludging' will ever be fixed?
  318.  
  319. ============================== Credits ===============================
  320. ======================================================================
  321. rexxhost.library  was  built  from example source code written by Gary
  322. Samad  &  Bill  Hawes (fancydemo.c), extensions & additional functions
  323. were created by Olaf 'Olsen' Barthel.
  324.  
  325. The  entire  contents  of  this  library  package  may be used for any
  326. purpose,  no  regard  whether commercial or non-commercial.  No credit
  327. must  be  given  to  the  creator, nor must a registration fee be paid
  328. (though I wouldn't mind if anybody did).
  329.  
  330.                      THIS IS TRULY PUBLIC DOMAIN!
  331.  
  332. =============================== Author ===============================
  333. ======================================================================
  334.  
  335.                       Olaf 'Olsen' Barthel, MXM
  336.                           Brabeckstrasse 35
  337.                           D-3000 Hannover 71
  338.  
  339.                      Federal Republic of Germany
  340.  
  341.                        Phone: (05 11) 52 23 38
  342.  
  343. ============ Revision history (most recent change first) =============
  344. ======================================================================
  345. 34.12   The  library  can  be recompiled using 16 bit integers now.  I
  346.         don't  know  if  anybody  profits  from  this feature but it's
  347.         included  anyway.   By  the  way:   code  size went up to 2912
  348.         bytes.
  349.  
  350. 34.11   The library  went through  the third major rewrite, along with
  351.         some  more cleanups (nobody told me that the NULL-function has
  352.         to   be  supported)  assembly  language  string-routines  were
  353.         introduced to reduce the amount of support-library code.  Code
  354.         size dropped to 2840 bytes.
  355.  
  356. 34.10   Some  more  cleanups  in  RexxStrCmp  and  other routines were
  357.         really  necessary.   As  a  result,  code size went up to 2900
  358.         bytes.
  359.  
  360. 34.9    Added  more sanity checks in the Rexx Host creation/management
  361.         procedure.  An extended MsgPort structure with additional type
  362.         data  holds  the interface now.  Library code and data are now
  363.         much  more  compact than in the previous releases (I spent two
  364.         additional days debugging the code). Library  size  should  be
  365.         2792 bytes now.
  366.  
  367. 34.8    ANSIfication,   more   cleanups,   added  RexxStrCmp,  rewrote
  368.         CreateRexxHost/DeleteRexxHost  to become shorter, made library
  369.         use #pragma calls rather than  to  rely  on  the  rexxglue.asm
  370.         output file. Code size went down to about 2764 bytes (original
  371.         size: 3512 bytes).
  372.  
  373. 34.7    Ported   to  Aztec  'C'  5.0,  the  strange  library  creation
  374.         procedure  consumed lots of time (in which the author consumed
  375.         lots of cups of coffee).
  376.  
  377. 1.6     Initial creation using MkLib & elib.
  378.